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Discovery of Web Services (DISCO) 

Early Draft, 06 July 2000 

Copyright© 2000 M icrosoft . All rights reserved. 

Introduction 

Web Services are described in one or more related documents using the SOAP Contract Language 
(SCL). This document proposes how SCL documents can be retrieved for a resource or collection of 
resources, e,g. how information about a service is discovered. Note that this discovery algorithm it is 
not limited to discovering information about web services; it can be used to find metadata about any 
resource. 

There are other existing mechanisms for discovery (DAV, RDF, ...) that are just as valid for discovering 
services. This document does not attempt to be an exhaustive list but instead proposes two lightweight & 
mechanisms that are likely to work with existing infrastructure. 

Notational Conventions 

The keywords "MUST", "MUST NOT", "REQUIRED", "SHA1X", "SHALL NOT" "SHOULD" 
-SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be ' 
interpreted as described in RFC-21 19 T2). 

™^ paCe P**™* Mdisco " " scl "> "schema" and "soap" used in this document are associated with 
the DISCO namespaces "Mp://schemas.xmisoap.or F /di^f./", " http://schen™s xmlsoaD.org/discn/ sgl/" 
hm2^/s^nmxiD]Sfta£ s or^^ and "httPj^seb^mas.xm1 soap.or g /di fiC n/ S o fl p y 

Status 

This draft represents the current thinking with regard to discovery of services within Microsoft. It is 
published by Microsoft for the purpose of informing interested parties of the current state of that 
thinking, not as a finished proposal or commitment to implement. Microsoft will not allow early 
implementation to constrain its ability to make changes to this specification prior to final release. 
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1. Discovery Algorithm 

The discovery algorithm is based on the existence of a discovery document fonnat (an XML grammar) 
A discovery document is the result of performing discovery on a resource. A discovery document 
contains links to other resources describing or otherwise related to the resource (Service Contracts 
Schemas, etc). A discovery document may refer to related discovery documents. The derails of the 
discovery document fonriat are covered in sectjfin_2. 

The following algorithm allows a client to retrieve a discovery document given the URL of a resource 
^e a^onthm is independent of what the URL represents. For example, it could be the URL of the site 
the URL of a folder within the site, the URL of a particular service wirhin the s^k! ' 

To obtain the dis cover y document D associated with a URL U- 

❖ Perform an HTTP GET on U producing response J? 

❖ If the HTTP content-type of R is "text/xmT: 

> If R contains a discovery document, it is the discovery document D 

*„ ^ iS 3an, -«y fcahe « Processing instruction within the content of R with at 
least the following attribute values: 

■ type='text/xmr 

■ altemate='yes' 

■ hrefe'172' 
Then 

■ Perform an HTTP GET on U2 producing response R2 

■ If R2 contains a discovery document, it is the discovery document D 

■ Otherwise, there is no discovery documenr D available for V 
0t herwi se ^ to" 8 is no discovery document D available for U 

*> If rhe HTTP content-type of J? is "text/html": 

> a t t^buteva^e^ lOTenCe ° f * ***** ° f * With at lea$t fol,owin S 

■ type^'texc/xmT 

■ rel='alternate' 

■ href=' U2' 
Then 

■ Perform an HTTP GET on V2 producing response R2 

■ If R2 contains a discovery document, it is the discovery document D 
• Otherwise, there is no discovery document D available 

v Otherwise, there is no document D available for U 

❖ C ^Sl^l T £ u a ^ 6&T f ° r °* reS P° nse 10 te considered a discovery document: 
v- The content-type of the HTTP response is "text/xmj" 

t ™T v^J e 1001 element COnfoims to *e discovery document format. 

♦ Either the XML namespace is not specified, or it matches that of the discovery document format. 

**hm^^ for more info^on on 

2. Discovery Document Format 
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The discovery document format is a container for elements that typically contain links (URLs) to 
resources that provide discovery information. If the URL's are relative, they are assumed to be relative 
to the location of the discovery document. 

The following example discovery document refers to another discovery document, a Service Contract 
document, a schema document, and HTML based documentation for the service. 

<di sco : di scovery> 

<disco:discoveryRef ref = ' folder /discovery' /> 

< — elements from other namespaces — > 
< /disco: discovery?* 

The schema for the discovery document is neutral as to what types of things are being discovered. It 
relies on elements from other namespaces to provide the actual linking mechanisms specific to a 
resource type or category. 

The only linking element defined intrinsically is discoveryRef, which refers to another discovery 
document. The value of the ref attribute is the URL of the discovery document. 

Discovery documents may include the XML namespace "http://schemas.xmlsoap•org/di$co/ ,, for the 
discovery tag. Programs processing these documents MUST read and understand the namespace and 
SHOULD reject documents where the namespace is present and different. 

Programs processing discovery documents SHOULD ignore any unrecognized elements under the 
discovery tag to allow extensibility of the format. 

A discovery document MAY have an XML style sheet processing instruction. 

3. SCL and discovery 

The following elements are defined by the XML namespace ii http://schemas.xmlsoap.org/disco/scly ,, for 
use within discovery documents- 

3.1 contractRef 

The contractRef element refers to service defined using the SOAP Contract Lan^aae (SCL) The 
value of the ref attribute is the URL of the document. The value of the optional docRef attribute is the 
URL to human readable documentation for the service. 

The following example refers to two service contracts: 
<disco : discovery> 

<scl: contractRef re£= 'ntyl . sdl '> 

<scl: contractRef ref - 'my2 . sdl ' docRef = 'my.htm' > 
< / di s co : di scovery> 

4, Schemas and discovery 

The following elements are defined by the XML namespace 

"http://schemas^m]soap.ors/disco/scheJna/ ,, for use within discovery documents. 
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4,1 schemaRef 

The schemaRef element refers to an XML schema. The value of the ref attribute is the URL of the 
schema. The optional targetNamespace attribute indicates the namespace of the schema. 

The following example refers to two schema*: 

<disco : discovery> 

<schema i schemaRef ref = ' myl . xsd ' t:argetNamespace= ' htcp : / /my . org/myl . xsd ' /> 
<:sch<*ma:schemaHef ref *»'my2 ,xsd' /> 
</ disco = discovery> 

5. SOAP and discovery 

The following elements are defined by the XML namespace "http^/schemas.xmlsoap.org/disco/soap/" 
for use within discovery documents. 

5.1 soap 

The soap element specifies the location of a soap service with a particular soap binding that has been 
defined m a SCL document. The binding attribute contains a QName value. The URI portion of the 
QName refers to the targetNamespace of a SCL document. The name portion of the QName refers to a 
binding within that SCL document. The value of the address attribute is the URL of me soap service. 

The following example provides information about two web services- 

<di s co : di 3 eovery > 

<soap : soap bindings ' myl = bindingl ' address= ' myl ' > 

<soap:soap bindlng='myi:binding2' address='myl'> 

<soap:soap bindings 'myl: bindingl- address='my2'> 
< / di sco : di scovery> 

Although this information is available by reading a SCL document, this lightweight mechanism allows 
easier processing by clients attempting to find the location of a service with a known binding. 
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